\cbstart
\subsection{High-Performance Wall-Clock Timers {\tt <upc\_tick.h>}}
\label{upc-tick}
\index{upc\_tick.h}
\index{\_\_UPC\_TICK\_\_}
\index{timer}
\index{tick counter}
\index{wall-clock}
\index{cycle counter}
\xchangenote[id=DB]{9}{SECTION ADDED}

\npf This subsection provides extensions of [ISO/IEC00 Sec 7.23].
    All the characteristics of library functions described
    in [ISO/IEC00 Sec 7.1.4] apply to these as well.  Implementations
    that support this interface shall predefine the feature macro
    {\tt \_\_UPC\_TICK\_\_} to the value 1.

{\bf Rationale}

\np The {\tt upc\_tick\_t} type and associated functions 
provide convenient and portable support for
querying high-precision system timers for obtaining high-precision wall-clock timings of
sections of code. Many hardware implementations offer access to high-performance timers
with a handful of instructions, providing timer precision and overhead that can
be several orders of magnitude better than can be obtained through the use of
existing interfaces in [ISO/IEC00] or POSIX (e.g. the {\tt gettimeofday()} system call).


\subsubsection{Standard header}

\npf The standard header is

\begin{verbatim}
    <upc_tick.h> 
\end{verbatim}

\np The header {\tt upc\_tick.h} defines two macros, and declares one type for manipulating time.

\paragraph{upc\_tick\_t Type}
\index{upc\_tick\_t}

\npf The following type is defined in {\tt upc\_tick.h}:

\begin{verbatim}
    upc_tick_t 
\end{verbatim}

\np {\tt upc\_tick\_t} is an unsigned integral type representing a quantity of abstract timer ticks,
whose ratio to wall-clock time is implementation-dependent and thread-dependent.

\np {\tt upc\_tick\_t} values are thread-specific quantities with a thread-specific
interpretation (e.g. they might represent a
hardware cycle count on a particular processor, starting at some arbitrary time in
the past).  More specifically,  {\tt upc\_tick\_t} values do {\it not} provide a
globally-synchronized timer (i.e. the simultaneous absolute tick values may
differ across threads), and furthermore the tick-to-wall-clock conversion ratio
might also differ across UPC threads (e.g. on a system with heterogenerous processor
clock rates, the tick values may advance at different rates for different UPC
threads). 

\np As a rule of thumb, {\tt upc\_tick\_t} values and intervals
obtained by {\it different} threads should never be directly
compared or arithmetically combined, without first converting the relevant tick
intervals to wall time intervals (using {\tt upc\_ticks\_to\_ns}).

\paragraph{{\tt UPC\_TICK\_MAX} and {\tt UPC\_TICK\_MIN}}
\index{UPC\_TICK\_MAX}
\index{UPC\_TICK\_MIN}

\npf The following macro values are defined in {\tt upc\_tick.h}:

\begin{verbatim}
    UPC_TICK_MAX
    UPC_TICK_MIN
\end{verbatim}

\np {\tt UPC\_TICK\_MAX} and {\tt UPC\_TICK\_MIN} are constants of type {\tt upc\_tick\_t}.
They respectively provide the
minimal and maximal values representable in a variable of type {\tt upc\_tick\_t}.

\subsubsection{upc\_tick\_t functions}

\paragraph{The {\tt upc\_ticks\_now} function}\ \\
\label{upc-ticks-now}

{\bf Synopsis}
\index{upc\_ticks\_now}

\npf\vspace{-2.5em}
 \begin{verbatim}
    #include <upc_tick.h>

    upc_tick_t upc_ticks_now();
\end{verbatim}

{\bf Description}

\np {\tt upc\_ticks\_now} returns the current value of the tick timer for the calling thread,
as measured from an arbitrary, thread-specific point of time in the past (which is fixed
during any given program execution).

\np The function always succeeds.

\paragraph{The {\tt upc\_ticks\_to\_ns} function}\ \\
\label{upc-ticks-to-ns}

{\bf Synopsis}
\index{upc\_ticks\_to\_ns}

\npf\vspace{-2.5em}
 \begin{verbatim}
    #include <upc_tick.h>
    #include <stdint.h>

    uint64_t upc_ticks_to_ns(upc_tick_t ticks);
\end{verbatim}

{\bf Description}

\np {\tt upc\_ticks\_to\_ns} converts a quantity of ticks obtained by the
calling thread into wall-clock nanoseconds.

\np The function always succeeds.

\np EXAMPLE 1: an example of the upc\_tick interface in use:
\begin{verbatim}
  #include <upc_tick.h>
  #include <stdio.h>

  upc_tick_t start = upc_ticks_now();
    compute_foo(); /* do something that needs to be timed */
  upc_tick_t end = upc_ticks_now();

  printf("Time was: %f seconds\n", upc_ticks_to_ns(end-start)/1.0E-9);
\end{verbatim}

\cbend
